.\"	$OpenBSD: mdoc.template,v 1.9 2004/07/02 10:36:57 jmc Exp $
.\"
.Dd July 24, 2007
.Dt pnotify 3
.Os
.Sh NAME
.Nm pnotify
.Nd event notification framework
.Sh SYNOPSIS
.In pnotify.h
.Pp
.Ft void
.Fn pnotify_init
.Ft "struct watch *"
.Fn watch_signal "int signum" "void (*cb)(int, void *)" "void *arg"
.Ft "struct watch *"
.Fn watch_fd "int fd" "void (*cb)(int, int, void *)" "void *arg"
.Ft "struct watch *"
.Fn "watch_timer" "time_t interval" "void (*cb)(void *)" "void *arg"
.Ft "struct watch *"
.Fn watch_cancel "struct watch *w"
.Pp
.Sh DESCRIPTION
The
.Nm
library provides a portable event notification framework.
.Pp
.Fn pnotify_init
initializes the event queue, and must be called before any of the other pnotify functions. The event
queue will be automatically destroyed when the thread exits.
.Pp
.Sh EVENTS
The mask parameter is composed of one
or more bitflags from the following list of events:
.Bl -column "Flag" "Meaning" -offset indent
.It Sy PN_CLOSE Ta "A file descriptor was closed by the remote end."
.It Sy PN_ERROR Ta "An error occurred in the kernel event queue."
.It Sy PN_READ\   Ta "Data can be read from a file descriptor without blocking."
.It Sy PN_TIMEOUT Ta "A user-defined time interval has elapsed."
.It Sy PN_WRITE Ta "Data can be written to a file descriptor without blocking."
.El
.Sh WATCHES
A watch is a set of events that an application wishes to be notified about.
There is a function for each different type of event that can be monitored.
All of the functions for creating watches take a `mask' parameter, which is a bitmask
of events to watch for. 
They also take a callback function that will be invoked when the event occurs.
The following functions are used to create watches:
.Pp
.Fn watch_signal
causes an event to be generated when a signal is received by the process. The signal
is otherwise blocked, and will not cause a signal handler to be run. 
.Pp
.Fn watch_fd
causes an event to be generated when an open file descriptor is ready for reading,
ready for writing, or closed by the remote end.
.Pp
.Fn watch_timer
causes an event to be generated at a regular interval.
.Pp
When a watch is created, a watch handle is returned. To delete the watch,
call 
.Fn watch_cancel
and pass the watch handle as an argument.
.Sh ACTIONS
Programs need to respond to events. When a watch is created, a callback function
can be provided. This callback function will be executed each time a matching
event occurs. It is also possible to process each event manually and construct
your own event loop.
.Pp
.Fn event_wait
waits for a single event to occur, and fills the pnotify_event structure with information
about the event.  If an error occurs in the underlying kernel event queue, an
event is returned with the PN_ERROR flag set.
.Pp
The event structure contains the following fields:
.Bd -literal
struct event {
	struct watch *watch;
        int mask;
};
.Ed
.Pp
.Fn event_dispatch
waits for events and invokes the apropriate callback when an event occurs. 
This function never returns, and is intended to serve as the applications main event loop.
.Sh RETURN VALUES
Functions which create watches return pointers to the newly created
watch structure, or NULL if an error occurred.
All other functions return zero if successful, or -1 if an error occurs.
.Sh EXAMPLES
TODO....
.Bd -literal
   { example here ... }
.Ed
.Pp
The next example shows how to use the
.Fn event_dispatch
function. If the SIGHUP signal is sent to the process, it prints out a message. After
five seconds, the program will terminate.
.Bd -literal
void got_signal(int signum)
{
	printf("got signal %d\\n", signum);
}

void got_timeout()
{
	printf("timed out\\n");
	exit(0);
}

int main(int argc, char **argv)
{
	pnotify_init();
	watch_signal(SIGHUP, got_signal, NULL);
	watch_timer(5, PN_ONESHOT, got_timeout, NULL);
	event_dispatch();
	/* NOTREACHED */
}
.Ed
.Sh THREADSAFETY
.Nm
is a multi-threaded library and is fully threadsafe. Each thread must call
.Fn pnotify_init
before using any other library functions. Each thread has its own
event list. 
.Sh SEE ALSO
.Xr kqueue 4
.\" .Sh STANDARDS
.Sh AUTHORS
Mark Heily <devel@heily.com>
.\" .Sh CAVEATS
.\" .Sh BUGS
